Jars top 5% March 1996

ProfileViewer Instructions
Gamelan cool applet

by Greg White

This Java application reads profiling information produced by the Java interpreter and displays it for easy interpretation.

These instructions accompany the .93 version of the ProfileViewer zip file.

Last revision August 12, 1996

Table of Contents

Installing ProfileViewer

Acquire and Install the Collections Package

ProfileViewer depends on Doug Lea's excellent collections package. Acquire the package and follow the installation instructions.

Unzip ProfileViewer.zip

Choose a directory for the .class files and unzip them into it.

Modify CLASSPATH

Add the directory that you unzipped the .class file into to the classpath environment variable.

While this is not absolutely necessary (you can change the current directory to the place where the .class files are before starting the java interpreter), it will save you some trouble later on. You can load files from within the ProfileViewer application via the FileDialog.

One of the side effects of changing directories from within the FileDialog seems to be that the java interpreter also changes its current directory (at least in Windows 95). If you have not set the classpath environment variable, the interpreter will fail because it cannot find the .class file anymore.

Creating a Profile File

You create a profile file for an application by running the java interpreter with the -prof option (e.g. java -prof MyApp).

The procedure for creating a profile file for an applet is similar. Type

java -prof sun.applet.AppletViewer app.html

where app.html is the HTML file you normally pass to the applet viewer. When profiling applets, you may find that there is much more profiling information than really want due to all of the supporting classes. Perhaps in the future, I will allow you to selectively filter classes in the method list.

Starting ProfileViewer

To start ProfileViewer, type:

java ProfileViewer Profile

where Profile optionally specifies the name of a profile file to load. If this parameter is not specified, ProfileViewer will start without loading a file.

The Screen

The main screen consists of three lists and a status line. The list to the left shows all methods known. The list to the upper right shows all callees (methods called by the currently selected method in the list to the left). The list to the lower right shows all callers (methods calling the currently selected method in the list to the left).

The format of each line in these lists is 

time calls method
where time and calls are shown as percentages by default, but they can be changed to show abolute values (time in milliseconds and calls by count).

All percentages are relative to the lifetime of the application. In the methods list, the percentage is an overall value for each method. In the callees list, percentages shown reflect calls made to each method from the selected method to the left. In the callers list, percentages shown reflect calls made from each method to the selected method to the left.

When showing absolute values, the methods list entries are totals for each method while in the callees and callers list, these numbers are only in relation to the selected method in the list on the left.

The status line at the bottom shows the full name of the currently selected method. This helps you to see names that might be otherwise too long.

Profiler Reference

Profile Menu

Load...

Opens the FileDialog to let you choose a profile file to load. Note that if you change directories with this dialog and you have not modified the classpath environment variable, the java interpreter will start generating exceptions.

Toggle Numbers

Toggles between the absolute and percentage display of numbers as described in the section about the screen.

Exit

Closes the application

Method Menu

Focus

Sends keyboard focus to the method list.

Sort...

Brings up the sort dialog to let you sort the methods.

Find...

Brings up the find dialog. Note that the focus does not automatically go to the TextField as I would like. If anyone knows how to do this, please let me know. If have tried TextField.requestFocus(), with no luck.

Repeat find

Repeats the last find.

Callee Menu

Focus

Sends keyboard focus to the callee list.

Go To

"Goes to" the currently selected callee. Makes the currently selected callee the currently selected method so that you can see its callees and callers.

Sort...

Brings up the sort dialog to let you sort the callees.

Caller Menu

Focus

Sends keyboard focus to the caller list.

Go To

"Goes to" the currently selected caller. Makes the currently selected caller the currently selected method so that you can see its callees and callers.

Sort...

Brings up the sort dialog to let you sort the callers.

Keyboard Shortcuts

The following shortcuts can be used to do most of the actions performable by menu options: 
KEY     PERFORMS

---     --------

t       Profile|Toggle Numbers

m       Method|Focus

f       Method|Find...

n       Method|Repeat find

e       Callee|Focus

d       Callee|Go to

r       Caller|Go to

u       Caller|Go to

General Usage Notes

Caveat

The information shown here is only as good as the information produced by the java interpreter. In some cases (especially recursion), the results don't seem to make any sense at all. If someone has pointers to better documentation about the profile information, I will be glad to include information here or change ProfileViewer to accommodate it.

Also note that Sun's documentation for javaprof (a text-based report tool for the profile file) says it will not work correctly for multi-threaded applications. I expect that this warning ought to be for the profile file itself, not just for javaprof.

Optimizing Your Program

See Java Optimization, maintained by Jonathan Hardwick for some excellent reading about optimization and Java.

If you are reading or writing files, use BufferedInputStream and BufferedOutputStream if at all possible. It really does make a big difference.

I found that java.awt.list.getSelectedIndex() can be very slow if you have a lot of items in the list...I ended up working around this in ProfileViewer by keeping track of the currently selected item myself.

Some Areas Where Work is Needed

Replacement for java.awt.list

I would really like to use another Component altogether...lists are slow to report the selected item and to pass on the selected event when there is a mouse click. They also don't display columns of information or even show horizontal scrollbars.

Send focus to the textfield automatically in the Find dialog

I have tried having the TextField requestFocus() during the Find dialog construction, but this is apparently ignored.

Keyboard shortcuts don't always work

If I click on the title bar of ProfileWindow, then press a key, the key event is apparently never delivered to my handleEven() method.

Revisions

March 12, 1996
Now using fixed-width font and space-padded numbers to that it is easier for the eye to follow columns of calls and times.
March 25, 1996
Documented how to create profiling information for applets. Thanks to David Moore for the tip.
May 1, 1996
Added Jars top 5% logo and Gamelan cool applet logo <grin>.
May 2, 1996
May 28, 1996
May 30, 1996
July 19, 1996
August 12, 1996